Crate unsafe_io[−][src]

Expand description

Non-owning unsafe I/O

The main types are:

Resource	Posix-ish type	Windows type	Platform-independent types
File/Pipe	`RawFd`	`RawHandle`	`UnsafeHandle` or `UnsafeFile`
Socket	`RawFd`	`RawSocket`	`UnsafeHandle` or `UnsafeSocket`
Any	`RawFd`	`RawHandleOrSocket`	`UnsafeHandle`

and the main traits are:

Type	`As` trait	`Into` trait	`From` trait
`RawFd`	`AsRawFd`	`IntoRawFd`	`FromRawFd`
`RawHandle`	`AsRawHandle`	`IntoRawHandle`	`FromRawHandle`
`RawSocket`	`AsRawSocket`	`IntoRawSocket`	`FromRawSocket`
`RawHandleOrSocket`	`AsRawHandleOrSocket`	`IntoRawHandleOrSocket`	`FromRawHandleOrSocket`

`UnsafeFile`	`AsUnsafeFile`	`IntoUnsafeFile`	`FromUnsafeFile`
`UnsafeSocket`	`AsUnsafeSocket`	`IntoUnsafeSocket`	`FromUnsafeSocket`
`UnsafeHandle`	`AsUnsafeHandle`	`IntoUnsafeHandle`	`FromUnsafeHandle`

A brief explanation of the naming convention:

“Raw” is for platform-specific types and traits, such as std’s RawFd, AsRawFd, RawHandle, AsRawHandle, and similar, as well as unsafe-io’s RawHandleOrSocket, AsRawHandleOrSocket, and similar. “Handle” in this context means a Windows HANDLE.

“Unsafe” is for minimal platform-independent abstractions on top of the platform-specific types, such as UnsafeHandle (abstracts over RawFd and RawHandleOrSocket), UnsafeFile (abstracts over RawFd and RawHandle), and UnsafeSocket (abstracts over RawFd and RawSocket). “Handle” in this context means any kind of I/O handle.

Ownership Guarantees

Update: The approach to ownership in this crate is expected to be superceded by the io-lifetimes crate, which provides a much simpler and safer API.

The AsUnsafe* and IntoUnsafe* trait functions return non-owning handles, however these traits do require types that implement them to guarantee that they own the handles. This differs from their AsRaw* and IntoRaw* counterparts, which do not require such a guarantee. This crate defines an OwnsRaw trait which is unsafe to implement and which allows types to declare that they own the handles they hold, allowing them to opt into the blanket AsUnsafe* and IntoUnsafe* implementations. See rust-lang/rust#76969 for further background.

Additional Utilities

This crates also defines several additional utilities:

UnsafeHandle has functions as_readable and as_writeable which return similar non-owning types UnsafeReadable and UnsafeWriteable, respectively, which implement Read and Write.
AsUnsafeFile has functions as_file_view, as_pipe_reader_view, and as_pipe_writer_view (enable the os_pipe feature), and AsUnsafeSocket has functions as_tcp_stream_view, as_tcp_listener_view, as_udp_socket_view, and as_unix_stream_view (on unix platforms), for obtaining a temporary view of a handle as various higher-level types.
AsUnsafeHandle has an eq_handle function, AsUnsafeFile has an eq_file function, and AsUnsafeSocket has an eq_socket function, for comparing whether two types hold the same handle, and are safe to call.
FromUnsafeFile has a from_filelike function, and FromUnsafeSocket has a from_socketlike function, for constructing a type from any type which implements IntoUnsafeFile, or IntoUnsafeSocket, respectively. Unlike in the corresponding “Raw” traits, these functions are safe to call.
AsUnsafeReadWriteHandle, AsRawReadWriteFd, and AsRawReadWriteHandleOrSocket are traits for working with types that implement both Read and Write and may contain either one handle (such as a socket) or two (such as stdin and stdout, or a pair of pipes).

Examples

To use the AsUnsafeHandle trait:

use unsafe_io::AsUnsafeHandle;

// Open a normal file.
let file = std::fs::File::open("Cargo.toml").unwrap();

// Extract the handle.
let unsafe_handle = file.as_unsafe_handle();

Many types implement AsUnsafeHandle, however very few types implement FromUnsafeHandle. Most types implement only FromUnsafeFile or FromUnsafeSocket instead. For an example that extracts a handle and constructs a new file, we use the IntoUnsafeFile and AsUnsafeFile traits:

use unsafe_io::{FromUnsafeFile, IntoUnsafeFile};

// Open a normal file.
let file = std::fs::File::open("Cargo.toml").unwrap();

// Consume the file, returning the handle.
let unsafe_file = file.into_unsafe_file();

// Construct a new file with the handle.
let file = unsafe { std::fs::File::from_unsafe_file(unsafe_file) };

To implement the AsUnsafeHandle trait for a type, implement the AsRawFd trait for Posix-ish platforms and the AsRawHandleOrSocket trait for Windows platforms, and then implement OwnsRaw:

#[cfg(not(windows))]
use unsafe_io::os::rsix::{AsRawFd, RawFd};
#[cfg(windows)]
use unsafe_io::os::windows::{AsRawHandleOrSocket, RawHandleOrSocket};
use unsafe_io::OwnsRaw;

struct MyType(std::fs::File);

#[cfg(not(windows))]
impl AsRawFd for MyType {
    fn as_raw_fd(&self) -> RawFd {
        self.0.as_raw_fd()
    }
}

#[cfg(windows)]
impl AsRawHandleOrSocket for MyType {
    fn as_raw_handle_or_socket(&self) -> RawHandleOrSocket {
        self.0.as_raw_handle_or_socket()
    }
}

// Safety: `MyType` owns its handle.
unsafe impl OwnsRaw for MyType {}

This requires unsafe because implementing OwnsRaw asserts that the type owns its raw handle. See the char-device crate for a complete example.

Modules

os

OS-specific functionality.

Structs

ReadHalf

Adapt an AsUnsafeReadWriteHandle implementation to implement AsUnsafeHandle with the read handle.

UnsafeFile

A non-owning unsafe I/O handle which on Windows is limited to handling what Windows considers to be RawHandles—mainly files and pipes.

UnsafeHandle

A non-owning unsafe I/O handle.

UnsafeReadable

A non-owning unsafe I/O handle that implements Read. Read functions are considered safe, so this type requires unsafe to construct.

UnsafeSocket

A non-owning unsafe I/O handle which on Windows is limited to handling what Windows considers to be RawSockets—mainly TCP streams and listeners and UDP sockets.

UnsafeWriteable

A non-owning unsafe I/O handle that implements Write. Write functions considered are safe, so this type requires unsafe to construct.

View

A non-owning view of a resource which dereferences to a &Target or &mut Target.

WriteHalf

Adapt an AsUnsafeReadWriteHandle implementation to implement AsUnsafeHandle with the write handle.